home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / embedded / ibm / sym_r3.arc / SIM_R3.DOC < prev    next >
Text File  |  1991-11-27  |  18KB  |  385 lines
  1. SIM_R3.DOC
  2.     I. Introduction
  3.        A. Who wrote sim_r3 and why
  4.        B. Disclaimer
  5.     II. Using sim_r3.exe
  6.        A. Items on the display
  7.        B. Explanation of commands
  8.     III. Recompiling sim_r3
  9.        A. For the IBM-PC
  10.           1. Using Microsoft C 5.0 or higher
  11.           2. Using another compiler
  12.        B. For non-IBM compatible machines
  13.  
  14. I. Introduction
  15. I. A. Who wrote sim_r3 and why
  16.  
  17.      All files in this archive were written entirely by myself, 
  18.      Joseph Schachner.  I can be contacted via Compuserve 
  19.      (73637,3437).
  20.  
  21. /* I, Amir Bernstein, have made several improvements and fixed
  22.    minor bugs, I can be contacted on FREEWARE BBS */
  23.  
  24.  
  25.      sim_r3 was written to support a project where I work which  
  26.      is planning to use a 68705R3.  Because the 68705 program and 
  27.      data memory is compeletly internal, debugging a running 68705 
  28.      is nearly impossible.  Of course, the 68705 can be emulated 
  29.      by hardware, at a cost of several thousand dollars.  This is 
  30.      an excellent debugging solution.  However, simulation with 
  31.      software provides a very good debugging environment for 
  32.      almost no cost.  sim_r3 is in use by another engineer at my 
  33.      workplace, and has already found several bugs.
  34.  
  35.  
  36. I. B. Disclaimer
  37.  
  38.      Although I am an experienced 6800 family programmer, and I 
  39.      took great care to insure the accuracy of this emulation, and 
  40.      several bugs have been found and fixed as the program has 
  41.      been used, I make no representation that this program in its 
  42.      current form is either bug free or will precisely meet your 
  43.      needs.  The source code is distributed in this archive for 
  44.      you to add (or change) any feature.  If you change and 
  45.      recompile sim_r3.exe, PLEASE do not distribute it without 
  46.      noting your changes in this file!
  47.  
  48.      Changes:
  49.      V1.21 - added clear of latched external interrupt to 
  50.           simulated reset routine in instr.c.  This change is 
  51.           present in the source code in this archive.  This was an 
  52.           omission in 1.2 and earlier, but the only symptom is, if 
  53.           you issue 'I' and then reset before simulating servicing 
  54.           the interrupt the interrupt persists. 8-July-1989 Joe 
  55.       Schachner
  56. /*   V2.00 - The major changes are the symbol table support (5 chars/label)
  57.         and the requirement(!) for VGA in order to support 50 line mode,
  58.         the source code can always be changed to allow for different
  59.         numbers of line per screen.
  60.          Additional changes to files are noted:
  61.          INSTR.C  -  Add MUL (actually implements MUL).
  62.              Add STOP, WAIT (do not actually STOP or WAIT).
  63.              Update timings for HC05 devices.
  64.              Add symbol table reference by "linked list".
  65.          INSTR2.C -  Add symbol table reference to JMP, JSR, BRANCH
  66.               these do not appear as cleanly in "assignment"
  67.               column but it is clear enough.
  68.              Add STOP, WAIT (CCR modify).
  69.              Fix TAX,TXA by masking off the upper byte.
  70.              Fix ROR,ROL by masking off the upper byte.
  71. V  I         SIM_MEM.C - sym_nmbr[], sym_tbl[] memory reference.
  72. E  M                     load_sym() is identical to load() but it is very
  73. R  P                     important(!!!) to specify the correct file with
  74. Y  O                     the symbol table since otherwise the program will
  75.    R                     get lost (it searches for the \f charcater the
  76.    T                     assembler inserts in the output listing in
  77.    A                     the load_sym_data() routine).
  78.    N                     sym_writef_init() initialized the memory "image"
  79.    T                     sym_writef() actually sets the "linked list".
  80.          SIM_R3.C -  sym_nmbr[], sym_tbl[] memory allocation.
  81.              add 'y' condition for keyboard input.
  82.  
  83. */
  84.  
  85.  
  86. II. Using sim_r3.exe
  87.  
  88.      Normally, one develops for a 6805 family processor using an 
  89.      assembler and possibly a linker.  The output from the 
  90.      development tools is a file containing Motorola hex format 
  91.      records (S0, S1 and S9).
  92.  
  93.      The simulator loads in the Motorola hex file in response to 
  94.      the 'L' command (see below).  By default trace display and 
  95.      log file capture are on.  The simulator responds to your 
  96.      commands input in either upper or lower case.
  97.  
  98.      Note: the simulator's trace log file is named "sim_r3.log" 
  99.      and is created in the current directory when the simulator 
  100.      is started.  If a file with the same name existed, it is 
  101.      replaced by the new (empty) file.
  102.  
  103.      sim_r3 is a very small program.  When compiled with Microsoft 
  104.      C 5.0, it is about 55,000 bytes.  /* QuickC yeilds 45K */
  105.      Therefore, even 256K of memory is more than enough.  If you
  106.      plan to turn on the log file (to capture the trace on disk),
  107.      it helps to have a hard disk to keep execution speed up.
  108.  
  109. II. A. Items on the display
  110.  
  111.      When sim_r3 is started, it puts up the following on the top 
  112.      seven lines of the display:
  113.  
  114. 68705R3 Simulator V1.2  6-July-1989              Disp+log ON    Halted
  115. R - disp/chg regs       L file - load Sx & reset        E - toggle TIE  G - Go
  116. T - trace on/off        B addr - Break at address (go)  I - /INT      S - Step
  117. X - Reset       M addr - Mem view/mod   Z - Disassem    H - Halt      Q - Quit
  118.  
  119. /*                                                      Y - symbol table    */
  120. ______________________________________________________________________________
  121.  
  122.      The top line (line 1) shows program status.  The next three 
  123.      lines list commands, which will be explained below. The fifth 
  124.      line is always blank.  The sixth line is where all commands 
  125.      appear as you type them, and where prompts and messages 
  126.      appear; this line will be referred to as the "prompt line".
  127.  
  128.      The next line (line 7) is a solid bar separating the fixed 
  129.      top portion of the screen from the trace display, which 
  130.      scrolls up from line 24 to line 8 and vanishes.  Disassembly 
  131.      also appears on lines 8 to 24.
  132.  
  133.      The status line shows the program revision, whether trace 
  134.      results will be displayed (and optionally captured to a 
  135.      file), and whether simulation is in progress.  The next 
  136.      section, "Explanation of commands", provides more information 
  137.      on these fields.
  138.  
  139. II. B. Explanation of commands
  140.  
  141.     R - display / change registers
  142.      Text similar to the following appears on the prompt line:
  143.  
  144.      PC= 100, A= 00, X= 00, SP= 07F, CCR=08 (I)  Change?(reg) _
  145.  
  146.      The user may enter (at least the first character of) the name 
  147.      of any register shown, sim_r3 will prompt for a new value.  
  148.      Press return without entering a register name to end this 
  149.      command without changing a register.  Note: the values of the 
  150.      registers are displayed and entered in hex.  Bits that are on 
  151.      in the condition code register are also shown using the 
  152.      characters HINZC.
  153.  
  154.     L file - Load Sx and reset
  155.      sim_r3 reads motorola hex records.  Only S1 and S9 records 
  156.      are significant.  Checksums are ignored.  Loading is 
  157.      extremely fast.  When the "S9" record is encountered the load 
  158.      terminates.  End of file without an "S9" record causes an 
  159.      error message to be displayed.
  160.  
  161.      If the load completes without error, a message similar to the 
  162.      following is displayed:
  163.  
  164.      File test.sx loaded
  165.  
  166.      When a hex file has been loaded, a simulated reset is 
  167.      automatically performed (see 'X' command), below.
  168.  
  169.     E - Toggle TIE in
  170.      sim_r3 simulates all four timer modes.  The 'E' command 
  171.      changes the state of the timer's external input.  The current 
  172.      state is displayed on the prompt line.  The effect of 
  173.      changing the state of the timer's external input depends on 
  174.      the mode set by bits 4 and 5 (TIE and TIN) in the Timer 
  175.      Control Register.  See section 5.3 of the MC68(7)05 R/U 
  176.      Series technical data book, Motorola ADI-977.
  177.  
  178.     G - Go
  179.      The 'Halted' label changes to 'Running' and simulation 
  180.      commences at the current PC.  The breakpoint address is 
  181.      unchanged.  Simulation will halt when the PC equals the 
  182.      breakpoint address on an opcode fetch, or if the 'H' command 
  183.      is entered (see below).
  184.  
  185.     T - Trace display (and logfile) on/off
  186.      If display is on when this command is entered, it is turned 
  187.      off.  Logfile capture is always off when display is off.  If 
  188.      display is off when this command is entered, the prompt 
  189.      "Enable logfile also?(Y/N) " will appear.  After the prompt 
  190.      is answered, the label on line one will say either "Display 
  191.      ON" or "Disp+Log ON".  The format of the log file is 
  192.      identical to that of the trace display.
  193.  
  194.      Note: simulation proceeds MUCH faster if the trace display is 
  195.      turned off.
  196.  
  197.      An example trace display (part of a log file) appears below.  
  198.      It was generated by the commands 'L test.sx', 'B 10b'.
  199.  
  200. 100  A6 55         LDA   #$55           101=>55 ACCUM<=55                     2
  201. 102  48            LSLA                 ACCUM=>55 ACCUM<=AA                   6
  202. 103  47            ASRA                 ACCUM=>AA ACCUM<=D5                  10
  203. 104  97            TAX                  X_REG<=D5                            12
  204. 105  BF 50         STX   $50            050<=D5                              17
  205. 107  3C 50         INC   $50            050=>D5 050<=D6                      23
  206. 109  26 FC         BNE   $107                                                27
  207. 107  3C 50         INC   $50            050=>D6 050<=D7                      33
  208. 109  26 FC         BNE   $107                                                37
  209. ^    ^             ^                     ^                                   ^
  210. |    |             |                     addr=>data (read)                   |
  211. |    |             |                     addr<=data (write)        Cycle count
  212. |    |             |                     All values in hex.         in decimal
  213. |    |             Assembly              Register names ACCUM,
  214. |    |             Mnemonics             X_REG, SP may appear.
  215. |    |
  216. |    Opcode and operand bytes for this instruction, in hex.
  217. |
  218. PC for opcode, in hex
  219.  
  220.      The example trace continues until finally location $50 
  221.      becomes zero and the BNE is not taken:
  222.  
  223. 109  26 FC         BNE   $107                                               437
  224. 107  3C 50         INC   $50            050=>FF 050<=00                     443
  225. 109  26 FC         BNE   $107                                               447
  226.  
  227.      At this point the prompt line shows "Breakpoint reached" and 
  228.      the simulation is halted.
  229.  
  230.     B addr - Go and break at addr
  231.      The breakpoint address is set from the address (in hex) 
  232.      following the 'B'. After that, operation is the same as 'G', 
  233.      above.  See 'T', above,  for an example of this command's 
  234.      usage.
  235.  
  236.     I - /INT
  237.      Latches an external interupt.  If the interrupt mask is not 
  238.      set sim_r3 will simulate interrupt response prior to 
  239.      beginning the next simulated instruction.
  240.  
  241.     S - Step
  242.      Simulate one instruction at the current PC.  Similar to 'G' 
  243.      except simulation is automatically halted after one 
  244.      instruction.  The breakpoint address is unchanged.
  245.  
  246.     X - Reset
  247.      sim_r3 simulates a reset, loading the PC from the reset 
  248.      vector, initializing the data direction registers and the 
  249.      timer, and the timer control register from the Mask Options 
  250.      Register, and setting the interrupt mask and resetting the 
  251.      stack pointer to 7F, and (version 1.21 and higher) also 
  252.      clears internal latched interrupt if any.
  253.  
  254.     M addr - memory view/change
  255.      The address (in hex) is read as if read by a program running 
  256.      in the 68705, and the address and value are displayed on the 
  257.      prompt line.  If 'Enter' is pressed, the next location is 
  258.      displayed.  If a hex value is entered, the value is written 
  259.      to the displayed location and then the next location is 
  260.      displayed.  To get out of this routine, enter a non-hex-digit 
  261.      ascii character, for example 'q'.
  262.      Example: M 100
  263.      100 A6      
  264.      101 55      
  265.      102 48  q
  266.  
  267.     Z - disassemble
  268.      Z displays assembly mnemonics for the next 15 instructions in 
  269.      memory starting at the current program counter, or, if an 
  270.      address is entered, for the next 15 instructions starting at 
  271.      that address.  The display looks similar to a trace display 
  272.      except no read/write data is shown and machine cycles are not 
  273.      shown.  Disassembly has no effect on simulation state.
  274.  
  275.     H - halt
  276.      If simulation is in progress, it is stopped.  The 'Running' 
  277.      label on the first line changes to 'Halted'.
  278.  
  279.     Q - quit
  280.      Leave sim_r3.  The following appears on the prompt line:
  281.      Logfile closed - normal exit
  282.  
  283.     Y - load symbol table.  As stipulated above it is necessary to
  284.      specify the correct file with the symbol table (generated by
  285.      the FREEWARE assembler on the BBS) to prevent the program from
  286.      locking up.
  287.  
  288.    Enter -
  289.      Just pressing 'Enter' does nothing but cause the line under 
  290.      the prompt line to be redrawn.  This is useful in case you 
  291.      accidentally press "Escape" and DOS blows away the line.
  292.  
  293. III. Recompiling sim_r3
  294.  
  295. III. A. For the IBM-PC
  296. III. A. 1. Using Microsoft C 5.0 or higher
  297.  
  298.      This supplied code may be compiled without changes.  The 
  299.      supplied make file, makefile.mak, is for Polytron's POLYMAKE 
  300.      to invoke the Microsoft C compiler.  The makefile is written 
  301.      in a manner which makes it very easy to convert for 
  302.      Microsoft's make, which is supplied with Microsoft C.  Only a 
  303.      few lines need to be moved.  Exact direction are in a comment 
  304.      in makefile.mak.
  305.  
  306. III. A. 2.Using another compiler
  307.  
  308.      Most of this program is "plain vanilla" C, and will port 
  309.      unchanged.  However, the functions which clear the screen and
  310.      position the text cursor are not portable.  clearscreen and 
  311.      settextposition call routines from Microsoft C 5.0's 
  312.      graphics library.  Most C compilers will supply library 
  313.      routines for these functions, which may be substituted.
  314.      Delete_line uses the Microsoft C function "int86" to invoke 
  315.      one of the DOS BIOS services.  Again, most C compiles for the 
  316.      PC will have some way to invoke the BIOS services, which may 
  317.      be substituted.
  318.  
  319.      If your compiler does NOT have cursor position and screen 
  320.      functions, you may use ANSI.SYS to supply these functions.  
  321.      ANSI.SYS is a file supplied with IBM DOS.  It may be built 
  322.      into the DOS of some clones.  ANSI.SYS must be memory 
  323.      resident.  This requires the statement "DEVICE=ANSI.SYS" in 
  324.      your config.sys file when you boot.  Then, simply writing a 
  325.      special sequence of characters to stdout will cause ANSI.SYS 
  326.      to perform these functions.  See the IBM DOS technical 
  327.      reference for documentation on control codes for ANSI.SYS.  
  328.      The code for using ANSI.SYS will look a lot like the code for 
  329.      driving a VT-52 (a Digital Equipment Corp terminal), which is 
  330.      included.  However, the control codes are not the same: 
  331.      ANSI.SYS uses DEC VT-100 control codes.
  332.  
  333.      sim.h includes a #define for the type of graphics routines, 
  334.      at the moment either MSC or VT52.  I suggest you add another 
  335.      #define and add your new C code right after each occurance of 
  336.      "#ifdef VT52 ... #endif" in the routines settextposition and 
  337.      clearscreen, both in sim_r3.c; and in the routine delete_line 
  338.      in instr.c.
  339.  
  340. III. B. For non-IBM compatible machines
  341.  
  342.      As long as your machine has an 80x25 character text display, 
  343.      the only changes which need to be made are to support the 
  344.      functions settextposition, clearscreen, and delete_line.
  345.  
  346.      sim.h includes a #define for the type of graphics routines, 
  347.      at the moment either MSC or VT52.  I suggest you add another 
  348.      #define and add your new C code right after each occurance of 
  349.      "#ifdef VT52 ... #endif" in the routines settextposition and 
  350.      clearscreen, both in sim_r3.c; and in the routine delete_line 
  351.      in instr.c.
  352.  
  353.      Note that if your computer emulates a DEC VT 52 terminal, or 
  354.      if you will use this on a computer that actually drives a 
  355.      terminal that can handle VT 52 control codes, then all you 
  356.      have to do is uncomment "#define VT52" instead of "#define 
  357.      MSC" in sim.h and recompile.
  358.  
  359.      It is interesting to note that exactly the same parts of the 
  360.      program need to be changed for a non-IBM compatible as for a 
  361.      true IBM compatible but not Microsoft C 5.0 or higher.  This 
  362.      is because of the lack of standardization of even the most 
  363.      rudimentary graphics functions; each compiler is different.  
  364.      Perhaps X Windows will finally change this sad situation.
  365.  
  366.      One further reflection on graphics standardization: I 
  367.      mentioned above that sim_r3 was about 55,000 bytes when 
  368.      compiled by Microsoft C 5.0.  When compiled by Mark Williams 
  369.      C for the Atari ST it is only about 36,000 bytes.  This 
  370.      difference is due mostly to the fact that support for the 
  371.      needed graphics functions and VT52 emulation is part of the 
  372.      ST's operating system, but requires routines from Microsoft C 
  373.      5.0's graphics library in the IBM version.  Consider the 
  374.      amount of memory wasted in a multitasking environment if each 
  375.      application includes the graphics library and ten or twenty 
  376.      applications are running...  This has nothing to do with 
  377.      sim_r3, but it's one of my favorite subjects!  My apologies.  
  378.      I hope sim_r3 is useful to you.
  379.  
  380.      --- Joe Schachner 8-July-1989
  381. /* Amir Bernstein 27-November-1991, Happy Thanksgiving Joe in case you
  382.    get this before Thanksgiving */
  383.  
  384.  
  385.